SSH Client PRO#

The SSHClient class provides an interface for connecting to a remote SSH server, executing commands, opening TTY or PTY sessions, transferring files via SFTP, and performing multi-hop SSH jumps. It supports both command-based and interactive terminal-based workflows.

This class is central to establishing and managing SSH sessions in your script.

Static Methods#

SSHClient.connect(options): Promise<SSHClient>#

Establishes a connection to a remote SSH server.

Parameters:#

• options (object):

  • host (string): The hostname or IP address of the SSH server.

  • port? (number): The port number to connect to. Defaults to 22.

  • authenticationMethod (SSHAuthenticationMethod): The authentication method to use (e.g., password, RSA key).

  • trustedHostKeys? (string[]): Optional list of trusted server public keys. If provided, the client will validate the server against this list.

  • reconnect? ("never" | "once" | "always"): Optional strategy for reconnecting if the connection drops. Default is "never".

Returns:#

• A Promise that resolves to an SSHClient instance upon successful connection.

Example:#

1const ssh = await SSHClient.connect({
2  host: "192.168.0.10",
3  authenticationMethod: SSHAuthenticationMethod.passwordBased("root", "password")
4})

Properties#

onDisconnect: (() => void) | null#

Callback function to be invoked when the SSH connection is lost or closed.

Example:#

1ssh.onDisconnect = () => {
2  console.log("Disconnected from SSH server.")
3}

Instance Methods#

executeCommand(command: string, options?): Promise<string>#

Executes a shell command on the remote server and returns its output.

Parameters:#

• command (string): The command to execute.

• options? (object):

  • maxResponseSize? (number): Maximum number of bytes to return.

  • includeStderr? (boolean): If true, includes standard error output in the result.

  • inShell? (boolean): If true, executes the command inside a shell (e.g., sh -c). Default is false.

Returns:#

• A Promise that resolves to the command output as a string.

Example:#

1const result = await ssh.executeCommand("uname -a")

executeCommandStream(command, onOutput, options?): Promise<void>#

Executes a command and streams its output line-by-line.

Parameters:#

• command (string): The command to run.

• onOutput (function): Callback (text: string, isStderr: boolean) => boolean Called for each line of output. Return false to stop receiving output.

• options?:

  • inShell? (boolean): Whether to run the command in a shell.

Returns:#

• A Promise that resolves when the command completes.

Example:#

1await ssh.executeCommandStream("ping -c 4 google.com", (text, isStderr) => {
2  console.log(text)
3  return true
4})

withPTY(options): Promise<TTYStdinWriter>#

Opens a PTY (pseudo-terminal) session.

Parameters:#

• options (object):

  • wantReply? (boolean): Whether to wait for a reply from the server. Defaults to true.

  • term? (string): Terminal type (default is "xterm").

  • terminalCharacterWidth? (number): Terminal character width. Default is 80.

  • terminalRowHeight? (number): Terminal row height. Default is 24.

  • terminalPixelWidth? (number): Terminal pixel width. Default is 0.

  • terminalPixelHeight? (number): Terminal pixel height. Default is 0.

  • onOutput (function): Callback (text: string, isStderr: boolean) => boolean for receiving terminal output.

  • onError? (function): Optional error callback (error: string) => void.

Returns:#

• A Promise that resolves to a TTYStdinWriter instance.

Example:#

1const writer = await ssh.withPTY({
2  onOutput: (text) => {
3    console.log(text)
4    return true
5  }
6})
7await writer.write("top\n")

withTTY(options): Promise<TTYStdinWriter>#

Opens a TTY session with simplified options (without explicit dimensions).

Parameters:#

• options (object):

  • onOutput (function): Callback for each line of output.

  • onError? (function): Callback for error reporting.

Returns:#

• A Promise that resolves to a TTYStdinWriter.

openSFTP(): Promise<SFTPClient>#

Opens an SFTP session for file transfer operations.

Returns:#

• A Promise that resolves to an SFTPClient instance.

Example:#

1const sftp = await ssh.openSFTP()
2await sftp.writeFile("/tmp/test.txt", "Hello world")

jump(options): Promise<SSHClient>#

Performs an SSH jump (proxy) to another remote host from the current SSH session.

Parameters:#

• options (object):

  • host (string): The destination host to jump to.

  • port? (number): Port to connect to (default is 22).

  • authenticationMethod (SSHAuthenticationMethod): Authentication method for the next host.

  • trustedHostKeys? (string[]): Optional list of trusted host keys.

Returns:#

• A Promise that resolves to a new SSHClient representing the jump connection.

Example:#

1const nextHop = await ssh.jump({
2  host: "10.0.0.2",
3  authenticationMethod: SSHAuthenticationMethod.passwordBased("user2", "pass2")
4})

close(): Promise<void>#

Closes the SSH connection and releases associated resources.

Important: You should call this method when the SSH client is no longer needed to avoid potential memory or socket leaks.

Returns:#

• A Promise that resolves when the SSH connection is successfully closed.

Example:#

1await ssh.close()

Usage Example#

1const ssh = await SSHClient.connect({
2  host: "192.168.1.10",
3  authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password")
4})
5
6const output = await ssh.executeCommand("uptime")
7console.log("Uptime:", output)
8
9const sftp = await ssh.openSFTP()
10await sftp.writeFile("/tmp/hello.txt", "Hello SSH")
11
12await ssh.close()